vLLM-Ascend 源码解读

vLLM-Ascend 是 vLLM 社区官方维护的昇腾 NPU 硬件插件，遵循 RFC: Hardware pluggable 的硬件可插拔设计，让 Transformer、MoE、Embedding、多模态等主流模型无需修改即可运行在昇腾 NPU 上。本文基于 v0.23.0 源码梳理其整体架构与核心模块。

一、项目定位

vLLM 本体通过 Platform 抽象层屏蔽硬件差异，vllm-ascend 作为独立插件在运行时注册 ascend 平台，接管设备管理、算子执行、通信与图引擎等能力。这种插件化设计的好处是：

• vLLM 主仓库保持硬件无关，昇腾适配代码独立演进、独立发版；
• 版本号与 vLLM 对齐（如 v0.23.0 对应 vLLM v0.23.x），升级节奏一致；
• 对上游的侵入性修改收敛到 patch/ 目录，便于跟随上游重构。

二、整体目录结构

vllm_ascend/
├── platform/            # 平台注册与设备能力声明
├── worker/              # Worker 与 ModelRunner（v1 / v2 两套）
│   └── v2/              #   新版执行路径：aclgraph、采样、投机解码
├── model_executor/      # offloader 卸载器、kernel 预热
├── model_loader/        # 权重加载：netloader 弹性加载、rfork
├── ops/                 # 自定义算子 + Triton kernel 库
│   ├── fused_moe/       #   MoE 融合算子（dispatcher、router、eplb）
│   ├── triton/          #   Triton kernels：rms_norm、rope、fla、kda、mamba…
│   └── …                #   mla、gdn、dsa、activation、layernorm…
├── quantization/        # 量化方法：w8a8 / w4a8 / w4a4 / wna16 / kv_cache
├── sample/              # 采样器与 rejection sampler
├── spec_decode/         # 投机解码 proposer：eagle / mtp / ngram / dflash / dspark
├── eplb/                # MoE 专家负载均衡策略（EPLB、FlashLB 等）
├── patch/               # 对上游 vLLM 的适配补丁（platform / worker）
├── _310p/               # Ascend 310P 专用实现分支
├── xlite/               # 轻量化执行路径
├── observability/       # 可观测性：metrics 导出
└── profiler/            # torch_npu profiler 集成

三、核心模块解读

1. Worker 与 ModelRunner

worker/ 是推理执行的核心。v1 路径（model_runner_v1.py）负责稳定版调度；v2 路径（worker/v2/）是重构后的新版执行器，拆分出 model_states（模型状态机）、sample/（top-k/top-p、penalties、logprob）、spec_decode/（各投机解码 speculator 的 aclgraph 实现）等子模块。aclgraph_utils.py 封装了昇腾 ACL Graph 等价于 CUDA Graph 的捕获与重放逻辑。

2. Triton 算子库（ops/triton/）

这是源码中最值得精读的部分，大量 kernel 用 Triton 编写以适配昇腾的 Triton 后端：

• 基础算子：rms_norm、rope、activation（swiglu_quant 等）、layernorm_gated；
• 线性注意力族：fla/（chunk_delta_h、chunk_o、l2norm 等，服务于 GDN/线性注意力模型）、kda/（Kendall Delta Attention 的 chunk 实现）、mamba/（causal_conv1d、lightning_attn）；
• 投机解码辅助：spec_decode/ngram、reject_sample、penalty；
• 确定性保障：batch_invariant/（matmul、softmax 等 batch 无关实现，保证数值一致性）。

每个 kernel 目录配有 docs/*.md 说明设计动机与实现细节，如 docs/rms_norm.md、docs/rope.md，是学习 Triton on Ascend 的第一手材料。

3. MoE 与 EPLB

ops/fused_moe/ 实现了完整的 MoE 执行链路：router（fused_topk / grouped_topk）、token dispatcher、shared/routed experts 与 finalize。eplb/ 提供专家负载均衡策略族：policy_default_eplb、policy_flashlb、policy_swift_balancer 等，由 policy_factory 统一创建，可在大规模 EP 部署下动态重排专家。

4. 量化体系（quantization/）

按 methods/ 下权重×激活位宽组织：

configs/ 中的 modelslim_config（华为 ModelSlim 工具链）、fp8_config、compressed_tensors_config 负责解析 HF 模型自带的量化配置。

5. 投机解码（spec_decode/）

proposer 体系覆盖了当前主流方案：eagle_proposer（EAGLE/EAGLE-3，含 vwn 变体）、dspark_proposer、dflash_proposer / dflash2_proposer、medusa_proposer、ngram_proposer（含 NPU 版）、draft_proposer（标准 MTP 草稿模型）、suffix_proposer。配套 models/ 下有 deepseek_v4、kimi_k3、qwen3、minimax_m3 等模型的 MTP/draft 权重适配，验证层则由 sample/rejection_sampler.py 与 v2 的 autoregressive speculator 承担。

6. Patch 适配层

patch/platform/ 与 patch/worker/ 收纳对上游 vLLM 的运行时补丁：KV Cache 管理、分布式（HCCL PG 注册）、CUDA Graph、多进程 Executor、投机配置等。patch_v2/ 对应新版执行路径。这一层的设计原则是"能不 patch 就不 patch"，随上游版本演进而收敛。

7. 其他值得关注的模块

• model_loader/netloader/：跨节点弹性权重加载（elastic_load），支持大模型分片并行拉取；rfork/ 提供基于 seed 同步的 fork 加速方案；
• model_executor/offloader/：CPU-NPU 权重/状态卸载与预取；warmup/ 在启动期预热 Triton kernel 避免首 token 抖动；
• _310p/：310P 这类较早硬件的专用 attention/MoE/量化实现；
• xlite/：面向极致启动速度的轻量执行路径。

四、建议的阅读路径

• 第一步：从 platform/ 入手，理解插件如何被 vLLM 发现与注册；
• 第二步：读 worker/model_runner_v1.py，串起一次完整推理的生命周期；
• 第三步：挑 ops/triton/docs/rms_norm.md + 对应 kernel 精读，掌握 Triton on Ascend 的写法；
• 第四步：按兴趣深入 fused_moe + eplb（MoE 部署）或 spec_decode（投机解码）；
• 第五步：对照 源码导航文档站逐模块阅读（每个 .py 都有对应解读页），并用 源码查看器直接浏览代码。

源码版本：vllm-ascend v0.23.0（main 分支） · 仅供学习交流